package org.vaadin.nf4v.core.handler;

import org.vaadin.nf4v.core.navigation.InvalidUriException;
import org.vaadin.nf4v.core.navigation.target.NavigationTarget;

/**
 * Param resolver is responsible for parsing parameters from string and creating string from parameters.
 * <p/>
 * In both cases two properties of NavigationTarget affected:
 * - paramsString
 * - params
 * Note: params map is represented LinedHashMap to preserve parameters order (which is very important for unnamed parameters)
 * <p/>
 * Different param resolver implementations may be used not only for playing with parameters separators, but for encoding
 * of entire string. E.g. if order id should be secured, it is possible to implement hex encoding for parameter string.
 * <p/>
 * OVERRIDING: may be overridden for context or page
 */
public interface ParamResolver extends Handler {

    /**
     * Uses paramsString from navigation target, parsed by UriHandler to prepare parameters map into params property
     * of navigation target. paramsString may contain null.
     *
     * @param target navigation target
     * @throws InvalidUriException on parameters parsing error
     */
    void resolveParameters(NavigationTarget target) throws InvalidUriException;

    /**
     * Uses params map of navigation target to create paramsString (used later by UriHandler to create page uri)
     *
     * @param target navigation target
     */
    void prepareParametersString(NavigationTarget target);
}
